Skip to content

Add JSDoc based types #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Apr 19, 2021
Merged

Add JSDoc based types #18

merged 3 commits into from
Apr 19, 2021

Conversation

wooorm
Copy link
Member

@wooorm wooorm commented Apr 18, 2021

Initial checklist

  • I read the support docs
  • I read the contributing guide
  • I agree to follow the code of conduct
  • I searched issues and couldn’t find anything (or linked relevant results below)
  • If applicable, I’ve added docs and tests

Description of changes

This changes from manual .d.ts files to JSDoc generated .d.ts files.

Notably, to review, here’s what the generated types look like:
/**
 * @typedef {import('unist').Node} Node
 * @typedef {import('unist').Parent} Parent
 *
 * @typedef {string} Type
 * @typedef {Object<string, unknown>} Props
 */
/**
 * Check if a node passes a test
 *
 * @callback TestFunctionAnything
 * @param {Node} node
 * @param {number} [index]
 * @param {Parent} [parent]
 * @returns {boolean|void}
 */
/**
 * Check if a node passes a certain node test
 *
 * @template {Node} X
 * @callback TestFunctionPredicate
 * @param {Node} node
 * @param {number} [index]
 * @param {Parent} [parent]
 * @returns {node is X}
 */
/**
 * @callback AssertAnything
 * @param {unknown} [node]
 * @param {number} [index]
 * @param {Parent} [parent]
 * @returns {boolean}
 */
/**
 * Check if a node passes a certain node test
 *
 * @template {Node} Y
 * @callback AssertPredicate
 * @param {unknown} [node]
 * @param {number} [index]
 * @param {Parent} [parent]
 * @returns {node is Y}
 */
/**
 * Check if a node passes a test.
 * When a `parent` node is known the `index` of node should also be given.
 *
 * @type {(
 *   (<T extends Node>(node: unknown, test?: null|undefined, index?: number, parent?: Parent, context?: unknown) => node is Node) &
 *   (<T extends Node>(node: unknown, test: T['type']|Partial<T>|TestFunctionPredicate<T>|Array.<T['type']|Partial<T>|TestFunctionPredicate<T>>, index?: number, parent?: Parent, context?: unknown) => node is T) &
 *   ((node?: unknown, test?: null|undefined|Type|Props|TestFunctionAnything|Array.<Type|Props|TestFunctionAnything>, index?: number, parent?: Parent, context?: unknown) => boolean)
 * )}
 */
export var is: (<T extends import('unist').Node>(
  node: unknown,
  test?: null | undefined,
  index?: number,
  parent?: Parent,
  context?: unknown
) => node is import('unist').Node) &
  (<T_1 extends import('unist').Node>(
    node: unknown,
    test:
      | T_1['type']
      | Partial<T_1>
      | TestFunctionPredicate<T_1>
      | Array<T_1['type'] | Partial<T_1> | TestFunctionPredicate<T_1>>,
    index?: number,
    parent?: Parent,
    context?: unknown
  ) => node is T_1) &
  ((
    node?: unknown,
    test?:
      | null
      | undefined
      | Type
      | Props
      | TestFunctionAnything
      | Array<Type | Props | TestFunctionAnything>,
    index?: number,
    parent?: Parent,
    context?: unknown
  ) => boolean)
/**
 * @type {(
 *   (<T extends Node>(test?: null|undefined) => AssertPredicate<Node>) &
 *   (<T extends Node>(test: T['type']|Partial<T>|TestFunctionPredicate<T>) => AssertPredicate<T>) &
 *   ((test?: null|undefined|Type|Props|TestFunctionAnything|Array.<Type|Props|TestFunctionAnything>) => AssertAnything)
 * )}
 */
export var convert: (<T extends import('unist').Node>(
  test?: null | undefined
) => AssertPredicate<Node>) &
  (<T_1 extends import('unist').Node>(
    test: T_1['type'] | Partial<T_1> | TestFunctionPredicate<T_1>
  ) => AssertPredicate<T_1>) &
  ((
    test?:
      | null
      | undefined
      | Type
      | Props
      | TestFunctionAnything
      | Array<Type | Props | TestFunctionAnything>
  ) => AssertAnything)
export type Node = import('unist').Node
export type Parent = import('unist').Parent
export type Type = string
export type Props = Record<string, unknown>
/**
 * Check if a node passes a test
 */
export type TestFunctionAnything = (
  node: Node,
  index?: number,
  parent?: Parent
) => boolean | void
/**
 * Check if a node passes a certain node test
 */
export type TestFunctionPredicate<X extends import('unist').Node> = (
  node: Node,
  index?: number,
  parent?: Parent
) => node is X
export type AssertAnything = (
  node?: unknown,
  index?: number,
  parent?: Parent
) => boolean
/**
 * Check if a node passes a certain node test
 */
export type AssertPredicate<Y extends import('unist').Node> = (
  node?: unknown,
  index?: number,
  parent?: Parent
) => node is Y

@wooorm wooorm added 🦋 type/enhancement This is great to have 🧑 semver/major This is a change ☂️ area/types This affects typings 👍 phase/yes Post is accepted and can be worked on labels Apr 18, 2021
@github-actions

This comment has been minimized.

@github-actions github-actions bot added 👋 phase/new Post is being triaged automatically 🤞 phase/open Post is being triaged manually and removed 👍 phase/yes Post is accepted and can be worked on 👋 phase/new Post is being triaged automatically labels Apr 18, 2021
@wooorm wooorm added the 👍 phase/yes Post is accepted and can be worked on label Apr 18, 2021
@github-actions github-actions bot removed the 🤞 phase/open Post is being triaged manually label Apr 18, 2021
@github-actions

This comment has been minimized.

Comment on lines +55 to +56
* (<T extends Node>(node: unknown, test: T['type']|Partial<T>|TestFunctionPredicate<T>|Array.<T['type']|Partial<T>|TestFunctionPredicate<T>>, index?: number, parent?: Parent, context?: unknown) => node is T) &
* ((node?: unknown, test?: null|undefined|Type|Props|TestFunctionAnything|Array.<Type|Props|TestFunctionAnything>, index?: number, parent?: Parent, context?: unknown) => boolean)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Impressive that it works, 👍
I'm looking foward to when JSDoc gets clearer syntax for overloading 😅

@wooorm wooorm merged commit f78c229 into main Apr 19, 2021
@wooorm wooorm deleted the ts branch April 19, 2021 07:17
@wooorm wooorm added the 💪 phase/solved Post is done label Apr 19, 2021
@github-actions github-actions bot removed the 👍 phase/yes Post is accepted and can be worked on label Apr 19, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
☂️ area/types This affects typings 💪 phase/solved Post is done 🧑 semver/major This is a change 🦋 type/enhancement This is great to have
Development

Successfully merging this pull request may close these issues.

2 participants